home *** CD-ROM | disk | FTP | other *** search
/ OpenGL Superbible (2nd Edition) / OpenGL SuperBible e2.iso / tools / Mesa-3.0 / SRC / DD.H < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-24  |  19.5 KB  |  572 lines
  1. /* $Id: dd.h,v 3.11 1998/08/23 22:18:18 brianp Exp $ */
  2.  
  3. /*
  4.  * Mesa 3-D graphics library
  5.  * Version:  3.0
  6.  * Copyright (C) 1995-1998  Brian Paul
  7.  *
  8.  * This library is free software; you can redistribute it and/or
  9.  * modify it under the terms of the GNU Library General Public
  10.  * License as published by the Free Software Foundation; either
  11.  * version 2 of the License, or (at your option) any later version.
  12.  *
  13.  * This library is distributed in the hope that it will be useful,
  14.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16.  * Library General Public License for more details.
  17.  *
  18.  * You should have received a copy of the GNU Library General Public
  19.  * License along with this library; if not, write to the Free
  20.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21.  */
  22.  
  23.  
  24. /*
  25.  * $Log: dd.h,v $
  26.  * Revision 3.11  1998/08/23 22:18:18  brianp
  27.  * added Driver.Viewport and Driver.DepthRange function pointers
  28.  *
  29.  * Revision 3.10  1998/06/07 22:19:31  brianp
  30.  * implemented GL_EXT_multitexture extension
  31.  *
  32.  * Revision 3.9  1998/04/22 00:52:42  brianp
  33.  * added GLcontext parameter to driver ExtensionString()
  34.  *
  35.  * Revision 3.8  1998/04/01 02:59:42  brianp
  36.  * updated for v0.24 of 3Dfx/Glide driver
  37.  *
  38.  * Revision 3.7  1998/03/28 03:57:39  brianp
  39.  * added CONST macro to fix IRIX compilation problems
  40.  *
  41.  * Revision 3.6  1998/03/10 01:28:09  brianp
  42.  * added a const keyword
  43.  *
  44.  * Revision 3.5  1998/02/21 01:01:07  brianp
  45.  * added GL_MAX_TEXTURES to GetParameteri() documentation
  46.  *
  47.  * Revision 3.4  1998/02/15 01:32:59  brianp
  48.  * updated driver bitmap function
  49.  *
  50.  * Revision 3.3  1998/02/07 14:43:35  brianp
  51.  * added GetParameteri() function
  52.  *
  53.  * Revision 3.2  1998/02/01 15:23:52  brianp
  54.  * added ExtensionString() function to device driver
  55.  *
  56.  * Revision 3.1  1998/01/31 23:57:23  brianp
  57.  * removed ClearDepthBuffer and ClearColorAndDepth functions
  58.  *
  59.  * Revision 3.0  1998/01/31 20:49:46  brianp
  60.  * initial rev
  61.  *
  62.  */
  63.  
  64.  
  65. #ifndef DD_INCLUDED
  66. #define DD_INCLUDED
  67.  
  68.  
  69. #include "macros.h"
  70.  
  71.  
  72. struct gl_pixelstore_attrib;
  73.  
  74.  
  75.  
  76. /* THIS FILE ONLY INCLUDED BY types.h !!!!! */
  77.  
  78.  
  79. /*
  80.  *                      Device Driver (DD) interface
  81.  *
  82.  *
  83.  * All device driver functions are accessed through pointers in the
  84.  * dd_function_table struct (defined below) which is stored in the GLcontext
  85.  * struct.  Since the device driver is strictly accessed trough a table of
  86.  * function pointers we can:
  87.  *   1. switch between a number of different device drivers at runtime.
  88.  *   2. use optimized functions dependant on current rendering state or
  89.  *      frame buffer configuration.
  90.  *
  91.  * The function pointers in the dd_function_table struct are divided into
  92.  * two groups:  mandatory and optional.
  93.  * Mandatory functions have to be implemented by every device driver.
  94.  * Optional functions may or may not be implemented by the device driver.
  95.  * The optional functions provide ways to take advantage of special hardware
  96.  * or optimized algorithms.
  97.  *
  98.  * The function pointers in the dd_function_table struct are first
  99.  * initialized in the "MakeCurrent" function.  The "MakeCurrent" function
  100.  * is a little different in each device driver.  See the X/Mesa, GLX, or
  101.  * OS/Mesa drivers for examples.
  102.  *
  103.  * Later, Mesa may call the dd_function_table's UpdateState() function.
  104.  * This function should initialize the dd_function_table's pointers again.
  105.  * The UpdateState() function is called whenever the core (GL) rendering
  106.  * state is changed in a way which may effect rasterization.  For example,
  107.  * the TriangleFunc() pointer may have to point to different functions
  108.  * depending on whether smooth or flat shading is enabled.
  109.  *
  110.  * Note that the first argument to every device driver function is a
  111.  * GLcontext *.  In turn, the GLcontext->DriverCtx pointer points to
  112.  * the driver-specific context struct.  See the X/Mesa or OS/Mesa interface
  113.  * for an example.
  114.  *
  115.  * For more information about writing a device driver see the ddsample.c
  116.  * file and other device drivers (xmesa[123].c, osmesa.c, etc) for examples.
  117.  *
  118.  *
  119.  * Look below in the dd_function_table struct definition for descriptions
  120.  * of each device driver function.
  121.  * 
  122.  *
  123.  * In the future more function pointers may be added for glReadPixels
  124.  * glCopyPixels, etc.
  125.  *
  126.  *
  127.  * Notes:
  128.  * ------
  129.  *   RGBA = red/green/blue/alpha
  130.  *   CI = color index (color mapped mode)
  131.  *   mono = all pixels have the same color or index
  132.  *
  133.  *   The write_ functions all take an array of mask flags which indicate
  134.  *   whether or not the pixel should be written.  One special case exists
  135.  *   in the write_color_span function: if the mask array is NULL, then
  136.  *   draw all pixels.  This is an optimization used for glDrawPixels().
  137.  *
  138.  * IN ALL CASES:
  139.  *      X coordinates start at 0 at the left and increase to the right
  140.  *      Y coordinates start at 0 at the bottom and increase upward
  141.  *
  142.  */
  143.  
  144.  
  145.  
  146.  
  147. /* Used by the GetParameteri device driver function */
  148. #define DD_MAX_TEXTURE_SIZE          0
  149. #define DD_MAX_TEXTURES              1
  150. #define DD_MAX_TEXTURE_COORD_SETS    2
  151. #define DD_HAVE_HARDWARE_FOG         3
  152.  
  153.  
  154.  
  155. /*
  156.  * Device Driver function table.
  157.  */
  158. struct dd_function_table {
  159.  
  160.    /**********************************************************************
  161.     *** Mandatory functions:  these functions must be implemented by   ***
  162.     *** every device driver.                                           ***
  163.     **********************************************************************/
  164.  
  165.    const char * (*RendererString)(void);
  166.    /*
  167.     * Return a string which uniquely identifies this device driver.
  168.     * The string should contain no whitespace.  Examples: "X11" "OffScreen"
  169.     * "MSWindows" "SVGA".
  170.     */
  171.  
  172.    void (*UpdateState)( GLcontext *ctx );
  173.    /*
  174.     * UpdateState() is called whenver Mesa thinks the device driver should
  175.     * update its state and/or the other pointers (such as PointsFunc,
  176.     * LineFunc, or TriangleFunc).
  177.     */
  178.  
  179.    void (*ClearIndex)( GLcontext *ctx, GLuint index );
  180.    /*
  181.     * Called whenever glClearIndex() is called.  Set the index for clearing
  182.     * the color buffer.
  183.     */
  184.  
  185.    void (*ClearColor)( GLcontext *ctx, GLubyte red, GLubyte green,
  186.                                         GLubyte blue, GLubyte alpha );
  187.    /*
  188.     * Called whenever glClearColor() is called.  Set the color for clearing
  189.     * the color buffer.
  190.     */
  191.  
  192.    GLbitfield (*Clear)( GLcontext *ctx, GLbitfield mask, GLboolean all,
  193.                         GLint x, GLint y, GLint width, GLint height );
  194.    /* Clear the color/depth/stencil/accum buffer(s).
  195.     * 'mask' indicates which buffers need to be cleared.  Return a bitmask
  196.     *    indicating which buffers weren't cleared by the driver function.
  197.     * If 'all' is true then the clear the whole buffer, else clear the
  198.     *    region defined by (x,y,width,height).
  199.     */
  200.  
  201.    void (*Index)( GLcontext *ctx, GLuint index );
  202.    /*
  203.     * Sets current color index for drawing flat-shaded primitives.
  204.     */
  205.  
  206.    void (*Color)( GLcontext *ctx,
  207.                   GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha );
  208.    /*
  209.     * Sets current color for drawing flat-shaded primitives.
  210.     */
  211.  
  212.    GLboolean (*SetBuffer)( GLcontext *ctx, GLenum mode );
  213.    /*
  214.     * Selects either the front or back color buffer for reading and writing.
  215.     * mode is either GL_FRONT or GL_BACK.
  216.     */
  217.  
  218.    void (*GetBufferSize)( GLcontext *ctx,
  219.                           GLuint *width, GLuint *height );
  220.    /*
  221.     * Returns the width and height of the current color buffer.
  222.     */
  223.  
  224.  
  225.    /***
  226.     *** Functions for writing pixels to the frame buffer:
  227.     ***/
  228.  
  229.    void (*WriteRGBASpan)( const GLcontext *ctx,
  230.                           GLuint n, GLint x, GLint y,
  231.                           CONST GLubyte rgba[][4], const GLubyte mask[] );
  232.    void (*WriteRGBSpan)( const GLcontext *ctx,
  233.                          GLuint n, GLint x, GLint y,
  234.                          CONST GLubyte rgb[][3], const GLubyte mask[] );
  235.    /* Write a horizontal run of RGB[A] pixels.  The later version is only
  236.     * used to accelerate GL_RGB, GL_UNSIGNED_BYTE glDrawPixels() calls.
  237.     */
  238.  
  239.    void (*WriteMonoRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
  240.                               const GLubyte mask[] );
  241.    /* Write a horizontal run of mono-RGBA pixels.
  242.     */
  243.  
  244.    void (*WriteRGBAPixels)( const GLcontext *ctx,
  245.                             GLuint n, const GLint x[], const GLint y[],
  246.                             CONST GLubyte rgba[][4], const GLubyte mask[] );
  247.    /* Write array of RGBA pixels at random locations.
  248.     */
  249.  
  250.    void (*WriteMonoRGBAPixels)( const GLcontext *ctx,
  251.                                 GLuint n, const GLint x[], const GLint y[],
  252.                                 const GLubyte mask[] );
  253.    /* Write an array of mono-RGBA pixels at random locations.
  254.     */
  255.  
  256.    void (*WriteCI32Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
  257.                           const GLuint index[], const GLubyte mask[] );
  258.    void (*WriteCI8Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
  259.                          const GLubyte index[], const GLubyte mask[] );
  260.    /* Write a horizontal run of CI pixels.  32 or 8bpp.
  261.     */
  262.  
  263.    void (*WriteMonoCISpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
  264.                             const GLubyte mask[] );
  265.    /* Write a horizontal run of mono-CI pixels.
  266.     */
  267.  
  268.    void (*WriteCI32Pixels)( const GLcontext *ctx,
  269.                             GLuint n, const GLint x[], const GLint y[],
  270.                             const GLuint index[], const GLubyte mask[] );
  271.    /*
  272.     * Write a random array of CI pixels.
  273.     */
  274.  
  275.    void (*WriteMonoCIPixels)( const GLcontext *ctx,
  276.                               GLuint n, const GLint x[], const GLint y[],
  277.                               const GLubyte mask[] );
  278.    /*
  279.     * Write a random array of mono-CI pixels.
  280.     */
  281.  
  282.  
  283.    /***
  284.     *** Functions to read pixels from frame buffer:
  285.     ***/
  286.  
  287.    void (*ReadCI32Span)( const GLcontext *ctx,
  288.                          GLuint n, GLint x, GLint y, GLuint index[] );
  289.    /* Read a horizontal run of color index pixels.
  290.     */
  291.  
  292.    void (*ReadRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
  293.                          GLubyte rgba[][4] );
  294.    /* Read a horizontal run of RGBA pixels.
  295.     */
  296.  
  297.    void (*ReadCI32Pixels)( const GLcontext *ctx,
  298.                            GLuint n, const GLint x[], const GLint y[],
  299.                            GLuint indx[], const GLubyte mask[] );
  300.    /* Read a random array of CI pixels.
  301.     */
  302.  
  303.    void (*ReadRGBAPixels)( const GLcontext *ctx,
  304.                            GLuint n, const GLint x[], const GLint y[],
  305.                            GLubyte rgba[][4], const GLubyte mask[] );
  306.    /* Read a random array of RGBA pixels.
  307.     */
  308.  
  309.  
  310.    /**********************************************************************
  311.     *** Optional functions:  these functions may or may not be         ***
  312.     *** implemented by the device driver.  If the device driver        ***
  313.     *** doesn't implement them it should never touch these pointers    ***
  314.     *** since Mesa will either set them to NULL or point them at a     ***
  315.     *** fall-back function.                                            ***
  316.     **********************************************************************/
  317.  
  318.    const char * (*ExtensionString)( GLcontext *ctx );
  319.    /* Return a space-separated list of extensions for this driver.
  320.     */
  321.  
  322.    void (*Finish)( GLcontext *ctx );
  323.    /*
  324.     * Called whenever glFinish() is called.
  325.     */
  326.  
  327.    void (*Flush)( GLcontext *ctx );
  328.    /*
  329.     * Called whenever glFlush() is called.
  330.     */
  331.  
  332.    GLboolean (*IndexMask)( GLcontext *ctx, GLuint mask );
  333.    /*
  334.     * Implements glIndexMask() if possible, else return GL_FALSE.
  335.     */
  336.  
  337.    GLboolean (*ColorMask)( GLcontext *ctx,
  338.                            GLboolean rmask, GLboolean gmask,
  339.                            GLboolean bmask, GLboolean amask );
  340.    /*
  341.     * Implements glColorMask() if possible, else return GL_FALSE.
  342.     */
  343.  
  344.    GLboolean (*LogicOp)( GLcontext *ctx, GLenum op );
  345.    /*
  346.     * Implements glLogicOp() if possible, else return GL_FALSE.
  347.     */
  348.  
  349.    void (*Dither)( GLcontext *ctx, GLboolean enable );
  350.    /*
  351.     * Enable/disable dithering.
  352.     */
  353.  
  354.    void (*Error)( GLcontext *ctx );
  355.    /*
  356.     * Called whenever an error is generated.  ctx->ErrorValue contains
  357.     * the error value.
  358.     */
  359.  
  360.    void (*NearFar)( GLcontext *ctx, GLfloat nearVal, GLfloat farVal );
  361.    /*
  362.     * Called from glFrustum and glOrtho to tell device driver the
  363.     * near and far clipping plane Z values.  The 3Dfx driver, for example,
  364.     * uses this.
  365.     */
  366.  
  367.    GLint (*GetParameteri)( const GLcontext *ctx, GLint param );
  368.    /* Query the device driver to get an integer parameter.
  369.     * Current parameters:
  370.     *     DD_MAX_TEXTURE_SIZE         return maximum texture size
  371.     *
  372.     *     DD_MAX_TEXTURES             number of texture sets/stages, usually 1
  373.     *
  374.     *     DD_HAVE_HARDWARE_FOG        the driver should return 1 (0 otherwise)
  375.     *                                 when the hardware support per fragment
  376.     *                                 fog for free (like the Voodoo Graphics)
  377.     *                                 so the Mesa core will start to ever use
  378.     *                                 per fragment fog
  379.     */
  380.  
  381.  
  382.    /***
  383.     *** For supporting hardware Z buffers:
  384.     ***/
  385.  
  386.    void (*AllocDepthBuffer)( GLcontext *ctx );
  387.    /*
  388.     * Called when the depth buffer must be allocated or possibly resized.
  389.     */
  390.  
  391.    GLuint (*DepthTestSpan)( GLcontext *ctx,
  392.                             GLuint n, GLint x, GLint y, const GLdepth z[],
  393.                             GLubyte mask[] );
  394.    void (*DepthTestPixels)( GLcontext *ctx,
  395.                             GLuint n, const GLint x[], const GLint y[],
  396.                             const GLdepth z[], GLubyte mask[] );
  397.    /*
  398.     * Apply the depth buffer test to an span/array of pixels and return
  399.     * an updated pixel mask.  This function is not used when accelerated
  400.     * point, line, polygon functions are used.
  401.     */
  402.  
  403.    void (*ReadDepthSpanFloat)( GLcontext *ctx,
  404.                                GLuint n, GLint x, GLint y, GLfloat depth[]);
  405.    void (*ReadDepthSpanInt)( GLcontext *ctx,
  406.                              GLuint n, GLint x, GLint y, GLdepth depth[] );
  407.    /*
  408.     * Return depth values as integers for glReadPixels.
  409.     * Floats should be returned in the range [0,1].
  410.     * Ints (GLdepth) values should be in the range [0,MAXDEPTH].
  411.     */
  412.  
  413.  
  414.    /***
  415.     *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions:
  416.     ***/
  417.  
  418.    points_func PointsFunc;
  419.    /* Called to draw an array of points.
  420.     */
  421.  
  422.    line_func LineFunc;
  423.    /*Called to draw a line segment.
  424.     */
  425.  
  426.    triangle_func TriangleFunc;
  427.    /* Called to draw a filled triangle.
  428.     */
  429.  
  430.    quad_func QuadFunc;
  431.    /* Called to draw a filled quadrilateral.
  432.     */
  433.  
  434.    rect_func RectFunc;
  435.    /* Called to draw a filled, screen-aligned 2-D rectangle.
  436.     */
  437.  
  438.    GLboolean (*DrawPixels)( GLcontext *ctx,
  439.                             GLint x, GLint y, GLsizei width, GLsizei height,
  440.                             GLenum format, GLenum type,
  441.                             const struct gl_pixelstore_attrib *unpack,
  442.                             const GLvoid *pixels );
  443.    /* Device driver hook for optimized glDrawPixels.  'unpack' describes how
  444.     * to unpack the source image data.
  445.     */
  446.  
  447.    GLboolean (*Bitmap)( GLcontext *ctx,
  448.                         GLint x, GLint y, GLsizei width, GLsizei height,
  449.                         const struct gl_pixelstore_attrib *unpack,
  450.                         const GLubyte *bitmap );
  451.    /* Device driver hook for optimized glBitmap.  'unpack' describes how
  452.     * to unpack the source image data.
  453.     */
  454.  
  455.    void (*Begin)( GLcontext *ctx, GLenum mode );
  456.    void (*End)( GLcontext *ctx );
  457.    /* These are called whenever glBegin() or glEnd() are called.
  458.     * The device driver may do some sort of window locking/unlocking here.
  459.     */
  460.  
  461.  
  462.    void (*RasterSetup)( GLcontext *ctx, GLuint start, GLuint end );
  463.    /* This function, if not NULL, is called whenever new window coordinates
  464.     * are put in the vertex buffer.  The vertices in question are those n
  465.     * such that start <= n < end.
  466.     * The device driver can convert the window coords to its own specialized
  467.     * format.  The 3Dfx driver uses this.
  468.     */
  469.  
  470.    GLboolean (*RenderVB)( GLcontext *ctx, GLboolean allDone );
  471.    /* This function allows the device driver to rasterize an entire
  472.     * buffer of primitives at once.  See the gl_render_vb() function
  473.     * in vbrender.c for more details.
  474.     * Return GL_TRUE if vertex buffer successfully rendered.
  475.     * Return GL_FALSE if failure, let core Mesa render the vertex buffer.
  476.     */
  477.  
  478.    /***
  479.     *** Texture mapping functions:
  480.     ***/
  481.  
  482.    void (*TexEnv)( GLcontext *ctx, GLenum pname, const GLfloat *param );
  483.    /*
  484.     * Called whenever glTexEnv*() is called.
  485.     * Pname will be one of GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
  486.     * If pname is GL_TEXTURE_ENV_MODE then param will be one
  487.     * of GL_MODULATE, GL_BLEND, GL_DECAL, or GL_REPLACE.
  488.     */
  489.  
  490.    void (*TexImage)( GLcontext *ctx, GLenum target,
  491.                      struct gl_texture_object *tObj, GLint level,
  492.                      GLint internalFormat,
  493.                      const struct gl_texture_image *image );
  494.    /*
  495.     * Called whenever a texture object's image is changed.
  496.     *    texObject is the number of the texture object being changed.
  497.     *    level indicates the mipmap level.
  498.     *    internalFormat is the format in which the texture is to be stored.
  499.     *    image is a pointer to a gl_texture_image struct which contains
  500.     *       the actual image data.
  501.     */
  502.  
  503.    void (*TexSubImage)( GLcontext *ctx, GLenum target,
  504.                         struct gl_texture_object *tObj, GLint level,
  505.                         GLint xoffset, GLint yoffset,
  506.                         GLsizei width, GLsizei height,
  507.                         GLint internalFormat,
  508.                         const struct gl_texture_image *image );
  509.    /*
  510.     * Called from glTexSubImage() to define a sub-region of a texture.
  511.     */
  512.  
  513.    void (*TexParameter)( GLcontext *ctx, GLenum target,
  514.                          struct gl_texture_object *tObj,
  515.                          GLenum pname, const GLfloat *params );
  516.    /*
  517.     * Called whenever glTexParameter*() is called.
  518.     *    target is GL_TEXTURE_1D or GL_TEXTURE_2D
  519.     *    texObject is the texture object to modify
  520.     *    pname is one of GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
  521.     *       GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_BORDER_COLOR.
  522.     *    params is dependant on pname.  See man glTexParameter.
  523.     */
  524.  
  525.    void (*BindTexture)( GLcontext *ctx, GLenum target,
  526.                         struct gl_texture_object *tObj );
  527.    /*
  528.     * Called whenever glBindTexture() is called.  This specifies which
  529.     * texture is to be the current one.  No dirty flags will be set.
  530.     */
  531.  
  532.    void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
  533.    /*
  534.     * Called when a texture object is about to be deallocated.  Driver
  535.     * should free anything attached to the DriverData pointers.
  536.     */
  537.  
  538.    void (*UpdateTexturePalette)( GLcontext *ctx,
  539.                                  struct gl_texture_object *tObj );
  540.    /*
  541.     * Called when the texture's color lookup table is changed.
  542.     * If tObj is NULL then the shared texture palette ctx->Texture.Palette
  543.     * was changed.
  544.     */
  545.  
  546.    void (*UseGlobalTexturePalette)( GLcontext *ctx, GLboolean state );
  547.    /*
  548.     * Called via glEnable/Disable(GL_SHARED_TEXTURE_PALETTE_EXT)
  549.     */
  550.  
  551.  
  552.    /***
  553.     *** NEW
  554.     ***/
  555.  
  556.    void (*Viewport)( GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h );
  557.    /*
  558.     * Called when viewport parameters are changed.
  559.     */
  560.  
  561.    void (*DepthRange)( GLcontext *ctx, GLclampd nearval, GLclampd farval );
  562.    /*
  563.     * Called when depth range parameters are changed.
  564.     */
  565.  
  566. };
  567.  
  568.  
  569.  
  570. #endif
  571.  
  572.